gsk: Documentation additions
authorMatthias Clasen <mclasen@redhat.com>
Mon, 25 Sep 2017 01:53:54 +0000 (21:53 -0400)
committerMatthias Clasen <mclasen@redhat.com>
Mon, 25 Sep 2017 02:26:39 +0000 (22:26 -0400)
Document newly added apis, and ensure that all public apis
are listed in the docs.

docs/reference/gsk/gsk4-sections.txt
gsk/gskrenderer.c
gsk/gskrendernode.c
gsk/gskrendernodeimpl.c
gsk/gskroundedrect.c
gsk/gsktexture.c

index a4498ca96018659502c8417b063a95480f1327f4..925c69412ff9278dafb2b78682714a73eb164755 100644 (file)
@@ -56,6 +56,7 @@ gsk_transform_node_get_child
 gsk_opacity_node_new
 gsk_opacity_node_get_child
 gsk_color_matrix_node_new
+gsk_color_matrix_node_get_child
 gsk_repeat_node_new
 gsk_clip_node_new
 gsk_clip_node_get_child
@@ -66,6 +67,8 @@ gsk_shadow_node_new
 GskBlendMode
 gsk_blend_node_new
 gsk_cross_fade_node_new
+gsk_text_node_new
+gsk_blur_node_new
 <SUBSECTION Standard>
 GSK_IS_RENDER_NODE
 GSK_RENDER_NODE
@@ -84,6 +87,7 @@ GSK_TYPE_SERIALIZATION_ERROR
 <SECTION>
 <FILE>GskTexture</FILE>
 gsk_texture_new_for_data
+gsk_texture_new_for_surface
 gsk_texture_new_for_pixbuf
 gsk_texture_get_width
 gsk_texture_get_height
@@ -99,6 +103,7 @@ GSK_IS_TEXTURE
 <FILE>GskRoundedRect</FILE>
 GskCorner
 GskRoundedRect
+GSK_ROUNDED_RECT_INIT
 gsk_rounded_rect_init
 gsk_rounded_rect_init_copy
 gsk_rounded_rect_init_from_rect
index 35747c9820ab1de68c4771020e6b626f5fa93af9..3e45766d6c4d67ebf976512a568c1ac77ee75aac 100644 (file)
@@ -967,6 +967,19 @@ gsk_renderer_begin_draw_frame (GskRenderer          *renderer,
   return priv->drawing_context;
 }
 
+/**
+ * gsk_renderer_end_draw_frame:
+ * @renderer: a #GskRenderer
+ * @context: the drawing context returned by the matching call to
+ *     gsk_renderer_begin_draw_frame()
+ *
+ * Release the drawning context returned by gsk_renderer_begin_draw_frame().
+ *
+ * Calls to gsk_renderer_begin_draw_frame() and gsk_renderer_end_draw_frame()
+ * must be paired.
+ *
+ * Since: 3.90
+ */
 void
 gsk_renderer_end_draw_frame (GskRenderer       *renderer,
                              GdkDrawingContext *context)
index 0954c5b0154a634abc7fea01519dbde5a007897e..53a23630e3af23233b489b6fc553d076798afd9e 100644 (file)
@@ -181,6 +181,17 @@ gsk_render_node_get_bounds (GskRenderNode   *node,
   graphene_rect_init_from_rect (bounds, &node->bounds);
 }
 
+/**
+ * gsk_render_node_set_scaling_filters:
+ * @node: a #GskRenderNode
+ * @min_filter: the filter for scaling down
+ * @mag_filter: the filter for scaling up
+ *
+ * Sets filters to be used when a node must be scaled up
+ * or down.
+ *
+ * Since: 3.90
+ */
 void
 gsk_render_node_set_scaling_filters (GskRenderNode    *node,
                                      GskScalingFilter  min_filter,
index c5d26b2a2e949842059322129ff91bdf141eea20..3dcd1cb521683069cada5ee2f9a7779ce933ab80 100644 (file)
@@ -333,10 +333,7 @@ gsk_linear_gradient_node_new (const graphene_rect_t  *bounds,
   g_return_val_if_fail (n_color_stops >= 2, NULL);
   g_return_val_if_fail (color_stops[0].offset >= 0, NULL);
   for (i = 1; i < n_color_stops; i++)
-    {
-      g_return_val_if_fail (color_stops[i].offset >= color_stops[i-1].offset, NULL);
-
-    }
+    g_return_val_if_fail (color_stops[i].offset >= color_stops[i-1].offset, NULL);
   g_return_val_if_fail (color_stops[n_color_stops - 1].offset <= 1, NULL);
 
   self = (GskLinearGradientNode *) gsk_render_node_new (&GSK_LINEAR_GRADIENT_NODE_CLASS, sizeof (GskColorStop) * n_color_stops);
@@ -351,6 +348,22 @@ gsk_linear_gradient_node_new (const graphene_rect_t  *bounds,
   return &self->render_node;
 }
 
+/**
+ * gsk_repeating_linear_gradient_node_new:
+ * @bounds: the rectangle to render the linear gradient into
+ * @start: the point at which the linear gradient will begin
+ * @end: the point at which the linear gradient will finish
+ * @color_stops: a pointer to an array of #GskColorStop defining the gradient
+ * @n_color_stops: the number of elements in @color_stops
+ *
+ * Creates a #GskRenderNode that will create a repeating linear gradient
+ * from the given points and color stops, and render that into the area
+ * given by @bounds.
+ *
+ * Returns: A new #GskRenderNode
+ *
+ * Since: 3.90
+ */
 GskRenderNode *
 gsk_repeating_linear_gradient_node_new (const graphene_rect_t  *bounds,
                                         const graphene_point_t *start,
@@ -368,10 +381,7 @@ gsk_repeating_linear_gradient_node_new (const graphene_rect_t  *bounds,
   g_return_val_if_fail (n_color_stops >= 2, NULL);
   g_return_val_if_fail (color_stops[0].offset >= 0, NULL);
   for (i = 1; i < n_color_stops; i++)
-    {
-      g_return_val_if_fail (color_stops[i].offset >= color_stops[i-1].offset, NULL);
-
-    }
+    g_return_val_if_fail (color_stops[i].offset >= color_stops[i-1].offset, NULL);
   g_return_val_if_fail (color_stops[n_color_stops - 1].offset <= 1, NULL);
 
   self = (GskLinearGradientNode *) gsk_render_node_new (&GSK_REPEATING_LINEAR_GRADIENT_NODE_CLASS, sizeof (GskColorStop) * n_color_stops);
@@ -2112,6 +2122,17 @@ gsk_container_node_get_n_children (GskRenderNode *node)
   return container->n_children;
 }
 
+/**
+ * gsk_container_node_get_child:
+ * @node: a container #GskRenderNode
+ * @idx: the position of the child to get
+ *
+ * Gets one of the children of @container.
+ *
+ * Returns: the @idx'th child of @container
+ *
+ * Since: 3.90
+ */
 GskRenderNode *
 gsk_container_node_get_child (GskRenderNode *node,
                               guint          idx)
@@ -2221,7 +2242,7 @@ gsk_transform_node_deserialize (GVariant  *variant,
                                        mat[8], mat[9], mat[10], mat[11],
                                        mat[12], mat[13], mat[14], mat[15]
                                    });
-                                    
+
   result = gsk_transform_node_new (child, &transform);
 
   gsk_render_node_unref (child);
@@ -2614,7 +2635,7 @@ gsk_color_matrix_node_deserialize (GVariant  *variant,
                                        mat[12], mat[13], mat[14], mat[15]
                                    });
   graphene_vec4_init (&offset, vec[0], vec[1], vec[2], vec[3]);
-                                    
+
   result = gsk_color_matrix_node_new (child, &matrix, &offset);
 
   gsk_render_node_unref (child);
@@ -2641,7 +2662,7 @@ static const GskRenderNodeClass GSK_COLOR_MATRIX_NODE_CLASS = {
  * Creates a #GskRenderNode that will drawn the @child with reduced
  * @color_matrix.
  *
- * In particular, the node will transform the operation  
+ * In particular, the node will transform the operation
  *   pixel = color_matrix * pixel + color_offset
  * for every pixel.
  *
@@ -2669,6 +2690,14 @@ gsk_color_matrix_node_new (GskRenderNode           *child,
   return &self->render_node;
 }
 
+/**
+ * gsk_color_matrix_node_get_child:
+ * @node: a color matrix @GskRenderNode
+ *
+ * Gets the child node that is getting its colors modified by the given @node.
+ *
+ * Returns: (transfer none): The child that is getting its colors modified
+ **/
 GskRenderNode *
 gsk_color_matrix_node_get_child (GskRenderNode *node)
 {
@@ -3994,6 +4023,20 @@ static const GskRenderNodeClass GSK_TEXT_NODE_CLASS = {
   gsk_text_node_deserialize
 };
 
+/**
+ * gsk_text_node_new:
+ * @font: the #PangoFont containing the glyphs
+ * @glyphs: the #PangoGlyphString to render
+ * @color: the foreground color to render with
+ * @x: the x coordinate at which to put the baseline
+ * @y: the y coordinate at wihch to put the baseline
+ *
+ * Creates a render node that renders the given glyphs,
+ * Note that @color may not be used if the font contains
+ * color glyphs.
+ *
+ * Since: 3.92
+ */
 GskRenderNode *
 gsk_text_node_new (PangoFont        *font,
                    PangoGlyphString *glyphs,
@@ -4322,6 +4365,15 @@ static const GskRenderNodeClass GSK_BLUR_NODE_CLASS = {
   gsk_blur_node_deserialize
 };
 
+/**
+ * gsk_blur_node_new:
+ * @child: the child node to blur
+ * @radius: the blur radius
+ *
+ * Creates a render node that blurs the child.
+ *
+ * Since: 3.92
+ */
 GskRenderNode *
 gsk_blur_node_new (GskRenderNode *child,
                    double         radius)
index 75c4e5a8aed8b90f24883a8262132f5cce498953..ce9757eff0afa72dbb6b353ae4f3108122a8a3b3 100644 (file)
@@ -500,7 +500,7 @@ gsk_rounded_rect_path (const GskRoundedRect *self,
   cairo_close_path (cr);
 }
 
-/*
+/*< private >
  * Converts to the format we use in our shaders:
  * vec4 rect;
  * vec4 corner_widths;
index f373aed045c636692f66541521934f862817f000..03691ff38867c736b02f0a915daf07a9a18cb877 100644 (file)
@@ -22,6 +22,8 @@
  * @Short_description: Pixel data uploaded to a #GskRenderer
  *
  * #GskTexture is the basic element used to refer to pixel data.
+ * It is primarily mean for pixel data that will not change over
+ * multiple frames, and will be used for a long time.
  *
  * You cannot get your pixel data back once you've uploaded it.
  *
@@ -135,7 +137,7 @@ gsk_texture_get_property (GObject    *gobject,
 
 static void
 gsk_texture_dispose (GObject *object)
-{    
+{
   GskTexture *self = GSK_TEXTURE (object);
 
   gsk_texture_clear_render_data (self);
@@ -277,6 +279,18 @@ gsk_cairo_texture_init (GskCairoTexture *self)
 {
 }
 
+/**
+ * gsk_texture_new_for_data:
+ * @data: the pixel data
+ * @width: the number of pixels in each row
+ * @height: the number of rows
+ * @stride: the distance from the beginning of one row to the next, in bytes
+ *
+ * Creates a new texture object holding the given data.
+ * The data is assumed to be in CAIRO_FORMAT_ARGB32 format.
+ *
+ * Returns: a new #GskTexture
+ */
 GskTexture *
 gsk_texture_new_for_data (const guchar *data,
                           int           width,
@@ -304,6 +318,15 @@ gsk_texture_new_for_data (const guchar *data,
   return texture;
 }
 
+/**
+ * gsk_texture_new_for_surface:
+ * @surface: a cairo image surface
+ *
+ * Creates a new texture object representing the surface.
+ * @surface must be an image surface with format CAIRO_FORMAT_ARGB32.
+ *
+ * Returns: a new #GskTexture
+ */
 GskTexture *
 gsk_texture_new_for_surface (cairo_surface_t *surface)
 {
@@ -391,6 +414,14 @@ gsk_pixbuf_texture_init (GskPixbufTexture *self)
 {
 }
 
+/**
+ * gsk_texture_new_for_pixbuf:
+ * @pixbuf: a #GdkPixbuf
+ *
+ * Creates a new texture object representing the GdkPixbuf.
+ *
+ * Returns: a new #GskTexture
+ */
 GskTexture *
 gsk_texture_new_for_pixbuf (GdkPixbuf *pixbuf)
 {